IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/u_man/cat1/perlapio.z/perlapio

Text File | 2002-10-03 | 15.4 KB | 397 lines

PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



NNNNAAAAMMMMEEEE
     perlapio - perl's IO abstraction interface.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
         PerlIO *PerlIO_stdin(void);
         PerlIO *PerlIO_stdout(void);
         PerlIO *PerlIO_stderr(void);

         PerlIO *PerlIO_open(const char *,const char *);
         int     PerlIO_close(PerlIO *);

         int     PerlIO_stdoutf(const char *,...)
         int     PerlIO_puts(PerlIO *,const char *);
         int     PerlIO_putc(PerlIO *,int);
         int     PerlIO_write(PerlIO *,const void *,size_t);
         int     PerlIO_printf(PerlIO *, const char *,...);
         int     PerlIO_vprintf(PerlIO *, const char *, va_list);
         int     PerlIO_flush(PerlIO *);

         int     PerlIO_eof(PerlIO *);
         int     PerlIO_error(PerlIO *);
         void    PerlIO_clearerr(PerlIO *);

         int     PerlIO_getc(PerlIO *);
         int     PerlIO_ungetc(PerlIO *,int);
         int     PerlIO_read(PerlIO *,void *,size_t);

         int     PerlIO_fileno(PerlIO *);
         PerlIO *PerlIO_fdopen(int, const char *);
         PerlIO *PerlIO_importFILE(FILE *, int flags);
         FILE   *PerlIO_exportFILE(PerlIO *, int flags);
         FILE   *PerlIO_findFILE(PerlIO *);
         void    PerlIO_releaseFILE(PerlIO *,FILE *);

         void    PerlIO_setlinebuf(PerlIO *);

         long    PerlIO_tell(PerlIO *);
         int     PerlIO_seek(PerlIO *,off_t,int);
         int     PerlIO_getpos(PerlIO *,Fpos_t *)
         int     PerlIO_setpos(PerlIO *,Fpos_t *)
         void    PerlIO_rewind(PerlIO *);

         int     PerlIO_has_base(PerlIO *);
         int     PerlIO_has_cntptr(PerlIO *);
         int     PerlIO_fast_gets(PerlIO *);
         int     PerlIO_canset_cnt(PerlIO *);









                                                                        PPPPaaaaggggeeee 1111






PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



         char   *PerlIO_get_ptr(PerlIO *);
         int     PerlIO_get_cnt(PerlIO *);
         void    PerlIO_set_cnt(PerlIO *,int);
         void    PerlIO_set_ptrcnt(PerlIO *,char *,int);
         char   *PerlIO_get_base(PerlIO *);
         int     PerlIO_get_bufsiz(PerlIO *);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     Perl's source code should use the above functions instead of those
     defined in ANSI C's _s_t_d_i_o._h.  The perl headers will #define them to the
     I/O mechanism selected at Configure time.

     The functions are modeled on those in _s_t_d_i_o._h, but parameter order has
     been "tidied up a little".

     PPPPeeeerrrrllllIIIIOOOO ****
         This takes the place of FILE *. Like FILE * it should be treated as
         opaque (it is probably safe to assume it is a pointer to something).

     PPPPeeeerrrrllllIIIIOOOO____ssssttttddddiiiinnnn(((()))), PPPPeeeerrrrllllIIIIOOOO____ssssttttddddoooouuuutttt(((()))), PPPPeeeerrrrllllIIIIOOOO____ssssttttddddeeeerrrrrrrr(((())))
         Use these rather than stdin, stdout, stderr. They are written to look
         like "function calls" rather than variables because this makes it
         easier to _m_a_k_e _t_h_e_m function calls if platform cannot export data to
         loaded modules, or if (say) different "threads" might have different
         values.

     PPPPeeeerrrrllllIIIIOOOO____ooooppppeeeennnn((((ppppaaaatttthhhh,,,, mmmmooooddddeeee)))), PPPPeeeerrrrllllIIIIOOOO____ffffddddooooppppeeeennnn((((ffffdddd,,,,mmmmooooddddeeee))))
         These correspond to _f_o_p_e_n()/_f_d_o_p_e_n() arguments are the same.

     PPPPeeeerrrrllllIIIIOOOO____pppprrrriiiinnnnttttffff((((ffff,,,,ffffmmmmtttt,,,,............)))), PPPPeeeerrrrllllIIIIOOOO____vvvvpppprrrriiiinnnnttttffff((((ffff,,,,ffffmmmmtttt,,,,aaaa))))
         These are _f_p_r_i_n_t_f()/_v_f_p_r_i_n_t_f() equivalents.

     PPPPeeeerrrrllllIIIIOOOO____ssssttttddddoooouuuuttttffff((((ffffmmmmtttt,,,,............))))
         This is _p_r_i_n_t_f() equivalent. printf is #defined to this function, so
         it is (currently) legal to use printf(fmt,...) in perl sources.

     PPPPeeeerrrrllllIIIIOOOO____rrrreeeeaaaadddd((((ffff,,,,bbbbuuuuffff,,,,ccccoooouuuunnnntttt)))), PPPPeeeerrrrllllIIIIOOOO____wwwwrrrriiiitttteeee((((ffff,,,,bbbbuuuuffff,,,,ccccoooouuuunnnntttt))))
         These correspond to _f_r_e_a_d() and _f_w_r_i_t_e(). Note that arguments are
         different, there is only one "count" and order has "file" first.

     PPPPeeeerrrrllllIIIIOOOO____cccclllloooosssseeee((((ffff))))

     PPPPeeeerrrrllllIIIIOOOO____ppppuuuuttttssss((((ffff,,,,ssss)))), PPPPeeeerrrrllllIIIIOOOO____ppppuuuuttttcccc((((ffff,,,,cccc))))
         These correspond to _f_p_u_t_s() and _f_p_u_t_c().  Note that arguments have
         been revised to have "file" first.

     PPPPeeeerrrrllllIIIIOOOO____uuuunnnnggggeeeettttcccc((((ffff,,,,cccc))))
         This corresponds to _u_n_g_e_t_c().  Note that arguments have been revised
         to have "file" first.





                                                                        PPPPaaaaggggeeee 2222






PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



     PPPPeeeerrrrllllIIIIOOOO____ggggeeeettttcccc((((ffff))))
         This corresponds to _g_e_t_c().

     PPPPeeeerrrrllllIIIIOOOO____eeeeooooffff((((ffff))))
         This corresponds to _f_e_o_f().

     PPPPeeeerrrrllllIIIIOOOO____eeeerrrrrrrroooorrrr((((ffff))))
         This corresponds to _f_e_r_r_o_r().

     PPPPeeeerrrrllllIIIIOOOO____ffffiiiilllleeeennnnoooo((((ffff))))
         This corresponds to _f_i_l_e_n_o(), note that on some platforms, the
         meaning of "fileno" may not match Unix.

     PPPPeeeerrrrllllIIIIOOOO____cccclllleeeeaaaarrrreeeerrrrrrrr((((ffff))))
         This corresponds to _c_l_e_a_r_e_r_r(), i.e., clears 'eof' and 'error' flags
         for the "stream".

     PPPPeeeerrrrllllIIIIOOOO____fffflllluuuusssshhhh((((ffff))))
         This corresponds to _f_f_l_u_s_h().

     PPPPeeeerrrrllllIIIIOOOO____tttteeeellllllll((((ffff))))
         This corresponds to _f_t_e_l_l().

     PPPPeeeerrrrllllIIIIOOOO____sssseeeeeeeekkkk((((ffff,,,,oooo,,,,wwww))))
         This corresponds to _f_s_e_e_k().

     PPPPeeeerrrrllllIIIIOOOO____ggggeeeettttppppoooossss((((ffff,,,,pppp)))), PPPPeeeerrrrllllIIIIOOOO____sssseeeettttppppoooossss((((ffff,,,,pppp))))
         These correspond to _f_g_e_t_p_o_s() and _f_s_e_t_p_o_s(). If platform does not
         have the stdio calls then they are implemented in terms of
         _P_e_r_l_I_O__t_e_l_l() and _P_e_r_l_I_O__s_e_e_k().

     PPPPeeeerrrrllllIIIIOOOO____rrrreeeewwwwiiiinnnndddd((((ffff))))
         This corresponds to _r_e_w_i_n_d(). Note may be redefined in terms of
         _P_e_r_l_I_O__s_e_e_k() at some point.

     PPPPeeeerrrrllllIIIIOOOO____ttttmmmmppppffffiiiilllleeee(((())))
         This corresponds to _t_m_p_f_i_l_e(), i.e., returns an anonymous PerlIO
         which will automatically be deleted when closed.

     CCCCoooo----eeeexxxxiiiisssstttteeeennnncccceeee wwwwiiiitttthhhh ssssttttddddiiiioooo

     There is outline support for co-existence of PerlIO with stdio.
     Obviously if PerlIO is implemented in terms of stdio there is no problem.
     However if perlio is implemented on top of (say) sfio then mechanisms
     must exist to create a FILE * which can be passed to library code which
     is going to use stdio calls.

     PPPPeeeerrrrllllIIIIOOOO____iiiimmmmppppoooorrrrttttFFFFIIIILLLLEEEE((((ffff,,,,ffffllllaaaaggggssss))))
         Used to get a PerlIO * from a FILE *.  May need additional arguments,
         interface under review.





                                                                        PPPPaaaaggggeeee 3333






PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



     PPPPeeeerrrrllllIIIIOOOO____eeeexxxxppppoooorrrrttttFFFFIIIILLLLEEEE((((ffff,,,,ffffllllaaaaggggssss))))
         Given an PerlIO * return a 'native' FILE * suitable for passing to
         code expecting to be compiled and linked with ANSI C _s_t_d_i_o._h.

         The fact that such a FILE * has been 'exported' is recorded, and may
         affect future PerlIO operations on the original PerlIO *.

     PPPPeeeerrrrllllIIIIOOOO____ffffiiiinnnnddddFFFFIIIILLLLEEEE((((ffff))))
         Returns previously 'exported' FILE * (if any).  Place holder until
         interface is fully defined.

     PPPPeeeerrrrllllIIIIOOOO____rrrreeeelllleeeeaaaasssseeeeFFFFIIIILLLLEEEE((((pppp,,,,ffff))))
         Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
         complete. It is removed from list of 'exported' FILE *s, and
         associated PerlIO * should revert to original behaviour.

     PPPPeeeerrrrllllIIIIOOOO____sssseeeettttlllliiiinnnneeeebbbbuuuuffff((((ffff))))
         This corresponds to _s_e_t_l_i_n_e_b_u_f(). Use is deprecated pending further
         discussion. (Perl core uses it _o_n_l_y when "dumping"; it has nothing to
         do with $| auto-flush.)

     In addition to user API above there is an "implementation" interface
     which allows perl to get at internals of PerlIO.  The following calls
     correspond to the various FILE_xxx macros determined by Configure. This
     section is really of interest to only those concerned with detailed
     perl-core behaviour or implementing a PerlIO mapping.

     PPPPeeeerrrrllllIIIIOOOO____hhhhaaaassss____ccccnnnnttttppppttttrrrr((((ffff))))
         Implementation can return pointer to current position in the "buffer"
         and a count of bytes available in the buffer.

     PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____ppppttttrrrr((((ffff))))
         Return pointer to next readable byte in buffer.

     PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____ccccnnnntttt((((ffff))))
         Return count of readable bytes in the buffer.

     PPPPeeeerrrrllllIIIIOOOO____ccccaaaannnnsssseeeetttt____ccccnnnntttt((((ffff))))
         Implementation can adjust its idea of number of bytes in the buffer.

     PPPPeeeerrrrllllIIIIOOOO____ffffaaaasssstttt____ggggeeeettttssss((((ffff))))
         Implementation has all the interfaces required to allow perl's fast
         code to handle <FILE> mechanism.

           PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                                 PerlIO_canset_cnt(f) && \
                                 `Can set pointer into buffer'


     PPPPeeeerrrrllllIIIIOOOO____sssseeeetttt____ppppttttrrrrccccnnnntttt((((ffff,,,,pppp,,,,cccc))))
         Set pointer into buffer, and a count of bytes still in the buffer.
         Should be used only to set pointer to within range implied by



                                                                        PPPPaaaaggggeeee 4444






PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



         previous calls to PerlIO_get_ptr and PerlIO_get_cnt.

     PPPPeeeerrrrllllIIIIOOOO____sssseeeetttt____ccccnnnntttt((((ffff,,,,cccc))))
         Obscure - set count of bytes in the buffer. Deprecated.  Currently
         used in only doio.c to force count < -1 to -1.  Perhaps should be
         PerlIO_set_empty or similar.  This call may actually do nothing if
         "count" is deduced from pointer and a "limit".

     PPPPeeeerrrrllllIIIIOOOO____hhhhaaaassss____bbbbaaaasssseeee((((ffff))))
         Implementation has a buffer, and can return pointer to whole buffer
         and its size. Used by perl for ----TTTT / ----BBBB tests.  Other uses would be
         very obscure...

     PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____bbbbaaaasssseeee((((ffff))))
         Return _s_t_a_r_t of buffer.

     PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____bbbbuuuuffffssssiiiizzzz((((ffff))))
         Return _t_o_t_a_l _s_i_z_e of buffer.





































                                                                        PPPPaaaaggggeeee 5555






PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))                                                        PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))























































                                                                        PPPPaaaaggggeeee 6666